.\" Author:	Juli Mallett <jmallett@FreeBSD.org>
.\" Date:	June 04, 2003
.\" Description:
.\" 	Manual page for libufs functions:
.\"		sbget(3)
.\"		sbsearch(3)
.\"		sbput(3)
.\"		sbread(3)
.\"		sbfind(3)
.\"		sbwrite(3)
.\"
.\" This file is in the public domain.
.\"
.Dd August 8, 2022
.Dt SBREAD 3
.Os
.Sh NAME
.Nm sbget , sbsearch , sbput , sbread , sbfind , sbwrite
.Nd read and write superblocks of a UFS file system
.Sh LIBRARY
.Lb libufs
.Sh SYNOPSIS
.In sys/param.h
.In sys/mount.h
.In ufs/ufs/ufsmount.h
.In ufs/ufs/dinode.h
.In ufs/ffs/fs.h
.In libufs.h
.Ft int
.Fn sbget "int devfd" "struct fs **fsp" "off_t sblockloc" "int flags"
.Ft int
.Fn sbsearch "int devfd" "struct fs **fsp" "int flags"
.Ft int
.Fn sbput "int devfd" "struct fs *fs" "int numaltwrite"
.Ft int
.Fn sbread "struct uufsd *disk"
.Ft int
.Fn sbfind "struct uufsd *disk" "int flags"
.Ft int
.Fn sbwrite "struct uufsd *disk" "int all"
.Sh DESCRIPTION
The
.Fn sbget ,
.Fn sbsearch ,
.Fn sbread ,
and
.Fn sbfind
functions provide superblock reads for
.Xr libufs 3
consumers.
The
.Fn sbput
and
.Fn sbwrite
functions provide superblock writes for
.Xr libufs 3
consumers.
.Pp
The
.Fn sbget
and
.Fn sbsearch
functions first allocate a buffer to hold the superblock.
Using the
.Va devfd
file descriptor that references the filesystem disk,
.Fn sbget
reads the superblock located at the byte offset specified by
.Va sblockloc
into the allocated buffer.
The value
.Cm UFS_STDSB
may be specified for
.Va sblockloc
to request that the standard location for the superblock be read.
The
.Fn sbsearch
function uses the
.Va devfd
file descriptor that references the filesystem disk,
to search first for the superblock at the standard location.
If it is not found or is too damaged to use
.Fn sbsearch
will attempt to find one of the filesystem's alternate superblocks.
Flags are specified by
.Em or Ns 'ing
the following values:
.Pp
.Bl -tag -width UFS_NOCSUM
.It Cm UFS_NOCSUM
Causes only the superblock itself to be returned, but does not read in any
auxiliary data structures like the cylinder group summary information.
.It Cm UFS_NOMSG
Indicates that superblock inconsistency error messages should not be printed.
.El
.Pp
If successful,
.Fn sbget
and
.Fn sbsearch
functions return a pointer to the buffer containing the superblock in
.Va fsp .
The
.Fn sbget
and
.Fn sbsearch
functions are safe to use in threaded applications.
.Pp
The
.Fn sbput
function writes the superblock specified by
.Va fs
to the location from which it was read on the disk referenced by the
.Va devfd
file descriptor.
Additionally, the
.Fn sbput
function will update the first
.Va numaltwrite
alternate superblock locations.
To update all the alternate superblocks,
specify a
.Va numaltwrite
value of
.Va fs->fs_ncg .
The
.Fn sbput
function is safe to use in threaded applications.
Note that the
.Fn sbput
function needs to be called only if the superblock has been
modified and the on-disk copy needs to be updated.
.Pp
The
.Fn sbread
function reads the standard filesystem superblock.
The
.Fn sbfind
function tries to find a usable superblock.
It searchs first for the superblock at the standard location.
If it is not found or is too damaged to use
.Fn sbfind
will attempt to find one of the filesystem's alternate superblocks.
If successful
.Fn sbread
and
.Fn sbfind
return a superblock in the
.Va d_sb ,
structure embedded in the given user-land UFS disk structure.
.Pp
The
.Fn sbwrite
function writes the superblock from the
.Va d_sb ,
structure embedded in the given user-land UFS disk structure
to the location from which it was read.
Additionally, the
.Fn sbwrite
function will write to all the alternate superblock locations if the
.Fa all
value is non-zero.
.Sh RETURN VALUES
.Rv -std sbread sbwrite
The
.Fn sbget ,
.Fn sbsearch ,
and
.Fn sbput
functions return the value 0 if successful;
otherwise they return one of the errors described below.
.Sh ERRORS
The errors returned by
.Fn sbget ,
.Fn sbsearch ,
.Fn sbread ,
and
.Fn sbfind ,
include any of the errors specified for the library function
.Xr bread 3 .
Additionally, they may follow the
.Xr libufs 3
error methodologies in situations where no usable superblock could be
found.
.Pp
The errors returned by
.Fn sbput
and
.Fn sbwrite
include any of the errors specified for the library function
.Xr bwrite 3 .
.Sh SEE ALSO
.Xr bread 3 ,
.Xr bwrite 3 ,
.Xr libufs 3
.Sh HISTORY
These functions first appeared as part of
.Xr libufs 3
in
.Fx 5.0 .
.Sh AUTHORS
.An Juli Mallett Aq Mt jmallett@FreeBSD.org
.An Marshall Kirk McKusick Aq Mt mckusick@FreeBSD.org
